Add GlobalSecondaryIndexDefinition for GSI container support by mbhaskar · Pull Request #47468 · Azure/azure-sdk-for-python

mbhaskar · 2026-06-12T00:19:34Z

Summary

Implements Global Secondary Index (GSI) container support in the Python Cosmos SDK, mirroring the Java SDK implementation (Azure/azure-sdk-for-java#48480).

A GSI container is a derived container built from a source container using a SQL projection query. The service already supports this; this PR adds the client-side support.

Changes

New files

azure/cosmos/_global_secondary_index.py — GlobalSecondaryIndexDefinition class with constructor validation, serialization (_to_dict/_from_dict), and read-only server-populated properties (source_container_rid, status)
tests/test_global_secondary_index.py — 20 unit tests covering constructor validation, serialization, deserialization, forward-compatibility
tests/test_global_secondary_index_live.py — Live integration tests using dedicated GSI test account

Modified files

azure/cosmos/__init__.py — Export GlobalSecondaryIndexDefinition
azure/cosmos/database.py — Added global_secondary_index_definition kwarg to create_container, create_container_if_not_exists, and replace_container (all overloads) with dual-write pattern
azure/cosmos/aio/_database.py — Async mirror of all sync changes
CHANGELOG.md — Feature entry
pytest.ini — Added cosmosGSI marker for live tests
live-platform-matrix.json — Added GSITestConfig matrix entry
tests.yml — Mapped gsi-pipeline-uri/gsi-pipeline-key KV secrets to env vars

Design Decisions

Dual-Write Pattern

For backward compatibility with older service versions, the SDK writes the GSI definition under both:

"globalSecondaryIndexDefinition" (new key)
"materializedViewDefinition" (legacy key)

On read, the new key is preferred with fallback to the legacy key.

Status as String Constants (not enum)

Status values ("Initializing", "InitialBuildAfterCreate", "InitialBuildAfterRestore", "Active", "DeleteInProgress") are kept as plain strings for forward-compatibility with future service-defined values.

Pattern Consistency

Follows the same integration pattern as computed_properties, vector_embedding_policy, full_text_policy, and change_feed_policy — kwarg extraction via kwargs.pop(), added to definition dict if not None.

Testing

All 20 unit tests pass
Live tests configured to use gsi-pipeline-uri/gsi-pipeline-key from KV (same secrets used by Java SDK pipeline)

Implement client-side support for Global Secondary Index (GSI) containers in the Python Cosmos SDK, mirroring the Java SDK implementation. Changes: - Add GlobalSecondaryIndexDefinition class with serialization/deserialization - Add global_secondary_index_definition keyword to create_container, create_container_if_not_exists, and replace_container (sync and async) - Implement dual-write pattern: writes to both globalSecondaryIndexDefinition and materializedViewDefinition keys for backward compatibility - Add comprehensive unit tests (20 tests) - Update CHANGELOG Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add 'cosmosGSI' pytest mark to pytest.ini - Add GSITestConfig matrix entry in live-platform-matrix.json - Add GSI_ACCOUNT_HOST/GSI_ACCOUNT_KEY env var mappings from Key Vault secrets (gsi-pipeline-uri, gsi-pipeline-key) in tests.yml - Create test_global_secondary_index_live.py with live tests for: - Creating GSI container with GlobalSecondaryIndexDefinition class - Creating GSI container with raw dict - create_container_if_not_exists with GSI definition Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR adds client-side support for Cosmos DB Global Secondary Index (GSI) containers in azure-cosmos, including a new GlobalSecondaryIndexDefinition model, plumbing through container create/replace APIs (sync + async) with a dual-write wire format, and CI/live-test wiring for a dedicated GSI-enabled account.

Changes:

Added GlobalSecondaryIndexDefinition (validation + (de)serialization) and exported it from azure.cosmos.
Added global_secondary_index_definition kwarg support to create_container, create_container_if_not_exists, and replace_container for both sync and async database clients (writing both globalSecondaryIndexDefinition and materializedViewDefinition).
Added unit + live tests plus pipeline/matrix/marker updates to run GSI live coverage.

Show a summary per file

File	Description
sdk/cosmos/tests.yml	Injects GSI account secrets as env vars for pipeline live runs.
sdk/cosmos/live-platform-matrix.json	Adds a dedicated matrix entry to run `cosmosGSI` marked live tests.
sdk/cosmos/azure-cosmos/tests/test_global_secondary_index.py	Unit tests for constructor validation and dict round-tripping.
sdk/cosmos/azure-cosmos/tests/test_global_secondary_index_live.py	Live tests that exercise creating GSI containers (class + raw dict).
sdk/cosmos/azure-cosmos/pytest.ini	Registers the new `cosmosGSI` pytest marker.
sdk/cosmos/azure-cosmos/CHANGELOG.md	Documents the new GSI feature in the Unreleased section.
sdk/cosmos/azure-cosmos/azure/cosmos/database.py	Adds sync API kwarg plumbing + dual-write of GSI definition in create/replace.
sdk/cosmos/azure-cosmos/azure/cosmos/aio/_database.py	Async mirror of sync GSI kwarg plumbing + dual-write behavior.
sdk/cosmos/azure-cosmos/azure/cosmos/_global_secondary_index.py	Introduces `GlobalSecondaryIndexDefinition` model implementation.
sdk/cosmos/azure-cosmos/azure/cosmos/init.py	Exports `GlobalSecondaryIndexDefinition` from the public package namespace.

Copilot's findings

Comments suppressed due to low confidence (1)

sdk/cosmos/azure-cosmos/CHANGELOG.md:11

The new changelog entry under "Features Added" is missing the usual reference/link to the PR (most other bullets in this section end with "See PR ####" or similar). Keeping the same format makes it easier to trace changes back to discussions and reviews.


#### Bugs Fixed

#### Other Changes

Files reviewed: 10/10 changed files
Comments generated: 1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dibahlfi · 2026-06-12T22:21:22Z

@sdkReviewAgent-2

dibahlfi · 2026-06-12T22:21:35Z

/azp run python - cosmos - tests

azure-pipelines · 2026-06-12T22:21:50Z

Azure Pipelines successfully started running 1 pipeline(s).

xinlian12 · 2026-06-12T23:00:31Z

✅ Review complete (38:22)

Posted 5 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

xinlian12 · 2026-06-12T23:01:14Z

✅ Review complete (38:58)

Posted 6 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

xinlian12 · 2026-06-12T23:09:45Z

✅ Review complete (47:54)

Posted 7 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

xinlian12 · 2026-06-12T23:27:38Z

✅ Review complete (05:21)

Posted 7 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

allenkim0129

Thank you for adding this. Overall, the updates look good to me, and Annie left good comments, but I have a comment related to the typehint. Please address it. Thanks!

- Move CHANGELOG entry to 4.16.2 (Unreleased) section - Add missing global_secondary_index_definition to sync replace_container overload 2 - Fix type hints: Optional[Any] -> Optional[Union[GlobalSecondaryIndexDefinition, dict[str, Any]]] - Add **provisional** marker to class and all kwarg docstrings - Add GSI docstrings to all async overloads (not just implementation methods) - Use public import in live tests - Add dual-write unit test Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Wrap :keyword docstring lines to stay within 120 char limit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 12, 2026 00:19

mbhaskar requested a review from a team as a code owner June 12, 2026 00:19

github-actions Bot added the Cosmos label Jun 12, 2026

github-project-automation Bot added this to CosmosDB Python Eco-System Jun 12, 2026

Copilot started reviewing on behalf of mbhaskar June 12, 2026 00:20 View session

mbhaskar and others added 2 commits June 11, 2026 17:21

mbhaskar force-pushed the mbhaskar/implement-gsi-containers branch from fef6964 to 713f56a Compare June 12, 2026 00:21

Copilot AI reviewed Jun 12, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/azure/cosmos/_global_secondary_index.py

Fix spelling error in live test (ifne -> notexist)

6489ceb

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>